<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, height=device-height, initial-scale=1, user-scalable=no">
  <meta name="generator" content="made with love by dartdoc 0.30.0+1">
  <meta name="description" content="retrofit API docs, for the Dart programming language.">
  <title>retrofit - Dart API docs</title>

  
  <link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500,400i,400,300|Source+Sans+Pro:400,300,700" rel="stylesheet">
  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
  <link rel="stylesheet" href="static-assets/github.css">
  <link rel="stylesheet" href="static-assets/styles.css">
  <link rel="icon" href="static-assets/favicon.png">
  <!-- header placeholder -->
</head>

<body>

<div id="overlay-under-drawer"></div>

<header id="title">
  <button id="sidenav-left-toggle" type="button">&nbsp;</button>
  <ol class="breadcrumbs gt-separated dark hidden-xs">
    <li><a href="https://mings.in/retrofit.dart/">retrofit package</a></li>
  </ol>
  <div class="self-name">retrofit</div>
  <form class="search navbar-right" role="search">
    <input type="text" id="search-box" autocomplete="off" disabled class="form-control typeahead" placeholder="Loading search...">
  </form>
</header>

<main>

  <div id="dartdoc-sidebar-left" class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left">
    <header id="header-search-sidebar" class="hidden-l">
      <form class="search-sidebar" role="search">
        <input type="text" id="search-sidebar" autocomplete="off" disabled class="form-control typeahead" placeholder="Loading search...">
      </form>
    </header>
    
    <ol class="breadcrumbs gt-separated dark hidden-l" id="sidebar-nav">
      <li><a href="https://mings.in/retrofit.dart/">retrofit package</a></li>
    </ol>
    
    <h5 class="hidden-xs"><span class="package-name">retrofit</span> <span class="package-kind">package</span></h5>
    <ol>
          <li class="section-title">Libraries</li>
          <li><a href="dio/dio-library.html">dio</a></li>
          <li><a href="http/http-library.html">http</a></li>
          <li><a href="retrofit/retrofit-library.html">retrofit</a></li>
    </ol>
  </div>

  <div id="dartdoc-main-content" class="col-xs-12 col-sm-9 col-md-8 main-content">
      <section class="desc markdown">
        <h1 id="retrofit-for-dart">Retrofit For Dart</h1>
<p><a href="https://circleci.com/gh/trevorwang/retrofit.dart"><img src="https://circleci.com/gh/trevorwang/retrofit.dart.svg?style=svg" alt="CircleCI"></a>
<a href="https://travis-ci.org/trevorwang/retrofit.dart"><img src="https://travis-ci.org/trevorwang/retrofit.dart.svg?branch=master" alt="Build Status"></a>
<a href="https://cloud.drone.io/trevorwang/retrofit.dart"><img src="https://cloud.drone.io/api/badges/trevorwang/retrofit.dart/status.svg" alt="Build Status"></a></p>
<p>retrofit.dart is a type conversion <a href="https://github.com/flutterchina/dio/">dio</a> client generator using <a href="https://github.com/dart-lang/source_gen">source_gen</a> and inspired by <a href="https://github.com/lejard-h/chopper">Chopper</a> and <a href="https://github.com/square/retrofit">Retrofit</a>.</p>
<h2 id="usage">Usage</h2>
<h3 id="generator">Generator</h3>
<p>Add the generator to your dev dependencies</p>
<pre class="language-yaml"><code class="language-yaml">dependencies:
  retrofit: any
  logger: any  #for logging purpose

dev_dependencies:
  retrofit_generator: any
  build_runner: any
</code></pre>
<h3 id="define-and-generate-your-api">Define and Generate your API</h3>
<pre class="language-dart"><code class="language-dart">import 'package:json_annotation/json_annotation.dart';
import 'package:retrofit/retrofit.dart';
import 'package:dio/dio.dart';

part 'example.g.dart';

@RestApi(baseUrl: "https://5d42a6e2bc64f90014a56ca0.mockapi.io/api/v1/")
abstract class RestClient {
  factory RestClient(Dio dio, {String? baseUrl}) = _RestClient;

  @GET("/tasks")
  Future&lt;List&lt;Task&gt;&gt; getTasks();
}

@JsonSerializable()
class Task {
  String id;
  String name;
  String avatar;
  String createdAt;

  Task({this.id, this.name, this.avatar, this.createdAt});

  factory Task.fromJson(Map&lt;String, dynamic&gt; json) =&gt; _$TaskFromJson(json);
  Map&lt;String, dynamic&gt; toJson() =&gt; _$TaskToJson(this);
}

</code></pre>
<p>then run the generator</p>
<pre class="language-sh"><code class="language-sh"># dart
pub run build_runner build

# flutter	
flutter pub run build_runner build
</code></pre>
<h3 id="use-it">Use it</h3>
<pre class="language-dart"><code class="language-dart">import 'package:logger/logger.dart';
import 'package:retrofit_example/example.dart';
import 'package:dio/dio.dart';

final logger = Logger();
void main(List&lt;String&gt; args) {
  final dio = Dio();   // Provide a dio instance
  dio.options.headers["Demo-Header"] = "demo header";   // config your dio headers globally
  final client = RestClient(dio);
  
  client.getTasks().then((it) =&gt; logger.i(it));
</code></pre>
<h2 id="more">More</h2>
<h3 id="type-conversion">Type Conversion</h3>
<blockquote>
<p>Before you use the type conversion, please make sure that a <code>factory Task.fromJson(Map&lt;String, dynamic&gt; json)</code> must be provided for each model class. <code>json_serializable</code> is the recommanded to be used as the serialization tool.</p>
</blockquote>
<pre class="language-dart"><code class="language-dart">...
@GET("/tasks")
  Future&lt;List&lt;Task&gt;&gt; getTasks();
}

@JsonSerializable()
class Task {
  String name;
  Task({this.name});
  factory Task.fromJson(Map&lt;String, dynamic&gt; json) =&gt; _$TaskFromJson(json);
}
</code></pre>
<h3 id="http-methods">HTTP Methods</h3>
<p>The HTTP methods in the below sample are supported.</p>
<pre class="language-dart"><code class="language-dart">  @GET("/tasks/{id}")
  Future&lt;Task&gt; getTask(@Path("id") String id);

  @PATCH("/tasks/{id}")
  Future&lt;Task&gt; updateTaskPart(
      @Path() String id, @Body() Map&lt;String, dynamic&gt; map);

  @PUT("/tasks/{id}")
  Future&lt;Task&gt; updateTask(@Path() String id, @Body() Task task);

  @DELETE("/tasks/{id}")
  Future&lt;void&gt; deleteTask(@Path() String id);

  @POST("/tasks")
  Future&lt;Task&gt; createTask(@Body() Task task);

  @POST("http://httpbin.org/post")
  Future&lt;void&gt; createNewTaskFromFile(@Part() File file);

  @POST("http://httpbin.org/post")
  @FormUrlEncoded()
  Future&lt;String&gt; postUrlEncodedFormData(@Field() String hello);
</code></pre>
<h3 id="get-original-http-reponse">Get original HTTP response</h3>
<pre class="language-dart"><code class="language-dart">  @GET("/tasks/{id}")
  Future&lt;HttpResponse&lt;Task&gt;&gt; getTask(@Path("id") String id)

  @GET("/tasks")
  Future&lt;HttpResponse&lt;List&lt;Task&gt;&gt;&gt;&gt; getTasks()
</code></pre>
<h3 id="http-header">HTTP Header</h3>
<ul>
<li>
<p>Add a HTTP header from the parameter of the method</p>
<pre class="language-dart"><code class="language-dart">  @GET("/tasks")
  Future&lt;Task&gt; getTasks(@Header("Content-Type") String contentType );
</code></pre>
</li>
</ul>
<ul>
<li>
<p>Add static HTTP headers</p>
<pre class="language-dart"><code class="language-dart">  @GET("/tasks")
  @Headers(&lt;String, dynamic&gt;{
      "Content-Type" : "application/json",
      "Custom-Header" : "Your header"
  })
  Future&lt;Task&gt; getTasks();
</code></pre>
</li>
</ul>
<h3 id="error-handling">Error Handling</h3>
<p><code>catchError(Object)</code> should be used for capturing the exception and failed response. You can get the detailed response info from <code>DioError.response</code>.</p>
<pre class="language-dart"><code class="language-dart"> client.getTask("2").then((it){
   logger.i(it);
 }).catchError((Object obj) {
    // non-200 error goes here.
    switch (obj.runtimeType) {
      case DioError:
        // Here's the sample to get the failed response error code and message
        final res = (obj as DioError).response;
        logger.e("Got error : ${res.statusCode} -&gt; ${res.statusMessage}");
        break;
      default:
    }
  });

}
</code></pre>
      </section>
      
        <section class="summary">
            <h2>Libraries</h2>
          <dl>
            <dt id="dio">
              <span class="name"><a href="dio/dio-library.html">dio</a></span>             
            </dt>
            <dd>
               
            </dd>
            <dt id="http">
              <span class="name"><a href="http/http-library.html">http</a></span>             
            </dt>
            <dd>
               
            </dd>
            <dt id="retrofit">
              <span class="name"><a href="retrofit/retrofit-library.html">retrofit</a></span>             
            </dt>
            <dd>
               
            </dd>
          </dl>
        </section>

  </div> <!-- /.main-content -->

  <div id="dartdoc-sidebar-right" class="col-xs-6 col-sm-6 col-md-2 sidebar sidebar-offcanvas-right">
  </div>

</main>

<footer>
  <span class="no-break">
    retrofit
      1.2.0
  </span>

  <!-- footer-text placeholder -->
</footer>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script src="static-assets/typeahead.bundle.min.js"></script>
<script src="static-assets/highlight.pack.js"></script>
<script src="static-assets/URI.js"></script>
<script id="dartdoc_script_js" src="static-assets/script.js"></script>
<!-- footer placeholder -->

</body>

</html>
